home *** CD-ROM | disk | FTP | other *** search
/ Fritz: All Fritz / All Fritz.zip / All Fritz / FILES / PROGNG_C / MDSPL100.LZH / MDISPLAY.DOC next >
Text File  |  1987-11-18  |  45KB  |  992 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.                                M D I S P L A Y
  26.  
  27.                        Secondary Monochrome I/O routines
  28.  
  29.                          Initial release, version 1.00
  30.  
  31.                copyright 1987 by William B. Bird
  32.  
  33.  
  34.  
  35.  
  36.                                     Shareware
  37.                                     ---------
  38.  
  39.  
  40.           This software is distributed as a shareware program.  Please
  41.        observe the following conditions:
  42.  
  43.           1) This software is not in the Public Domain.  It is owned and
  44.          copyrighted by the author.
  45.  
  46.           2) You may copy and distribute the software to whomever you wish,
  47.              but must distribute it intact, with no modifications.
  48.  
  49.           3) You may not charge for the software, except for the actual cost
  50.              to copy the software (not to exceed $10.00).  BBS's may restrict
  51.              access to fee paying registered users, at the SYSOP's
  52.              discretion.
  53.  
  54.           4) You may not take credit for the software.
  55.  
  56.           5) The software, when distributed, must have ALL of it's files.
  57.  
  58.           6) If you like the software, and deem it to be of value to you,
  59.              you may contribute any Dollar amount you feel is deserving
  60.              to the author.  Contributions of $25 or larger will entitle
  61.              the contributor to the next release of this software by direct
  62.              mail.
  63.  
  64.           7) The requirements above do not apply to executable files which
  65.              have the MDISPLAY routines linked into them.  The author makes
  66.              no royalty or other requirements to software which includes
  67.              these routines except that any commercial use must be registered
  68.              with the author and must include a contribution of $25 or more.
  69.  
  70.           8) With the current release, the source of the actual I/O routines
  71.              is not included.  Source for these routines may be available to
  72.              registered users ($25 donation).  Contact the author if this is
  73.              a requirement.
  74.  
  75.  
  76.  
  77.           User supported software is an attempt to provide quality software
  78.        at low cost to both the provider and the user.  The cost of a software
  79.        offering through conventional channels is very large, resulting in high
  80.        prices and the inability of independent authors and small companies
  81.        to develope and promote new products.  User supported software is an
  82.        attempt to develop a new, low cost, marketing channel for software
  83.        distribution.
  84.  
  85.           If the user supported software concept works, then everyone will
  86.        benefit.  The user will benefit by receiving quality products at a
  87.        low cost and by being able to throughly evaluate the product before
  88.        buying it.  The author benefits by being able to enter the software
  89.        market without the high front end costs and risks.  Unfortunately,
  90.        this concept can only work if all software users honor the author's
  91.        request for support.  If you, as a software user, benefit from a
  92.        "shareware" program then it must be worth something to you.  If so,
  93.        you should send a contribution to the author.  Without contributions,
  94.        good software authors will not be able to supply and support the high
  95.        quality software that is required.
  96.  
  97.  
  98.                                    Installation
  99.                                    ------------
  100.  
  101.           This computer program will run on IBM PC's and true compatibles,
  102.        which have both a color card (or EGA) and monitor and a monochrome card
  103.        and monitor.  The initialization routines will attempt to determine
  104.        whether the hardware configuration is appropriate and, if not, return
  105.        an error indication.  If you run into a situation where you believe
  106.        that the hardware is approriate and the software does not work as
  107.        described, please contact the author.
  108.  
  109.           This software is not copy protected.
  110.  
  111.           The software, as supplied, is written in, and compatable with
  112.        Microsoft C version 4.0.  Future releases will be available for MSC
  113.        version 5.0, and Borland's Turbo Pascal version 4.0 as they are
  114.        released.  Other Microsoft and Borland products may be compatable with
  115.        these releases.  If you have a specific compatability requirement,
  116.        feel free to contact the author about that requirement.
  117.  
  118.           The supplied disk includes the following files:
  119.  
  120.        README   TXT  Program overview and file list
  121.        MDISPLAY DOC  Mdisplay routine documentation
  122.        MDISPLAY H    C include file for entry points and variables
  123.        MDISPLAY OBJ  Mdisplay routines in OBJ format
  124.        MDISPLAY LIB  Mdisplay routines in MS LIB format
  125.        MDSPDEMO      Make file for mdisplay demo
  126.        MDSPDEMO C    Source for mdisplay demo
  127.        MDSPDEMO EXE  Executable file for mdisplay demo
  128.        MDSPTEE       Make file for mdisplay tee utility
  129.        MDSPTEE  C    Source file for mdisplay tee utility
  130.        MDSPTEE  EXE  Executable file for mdisplay tee utility
  131.        MDSP          Make file for MDSP utilities
  132.        MDSP     BAT  Test batch file for MDSP utilities
  133.        MDSPI    C    Source file for program to initialize monochrome
  134.                      display
  135.        MDSPI    EXE  Executable file for program to initialize monochrome
  136.                      display
  137.        MDSP1    C    Source file for program to write to the left half of
  138.                      the monochrome screen
  139.        MDSP1    EXE  Executable file for program to write to the left half
  140.                      of the monochrome screen
  141.        MDSP2    C    Source file for program to write to the right half of
  142.                      the monochrome screen
  143.        MDSP2    EXE  Executable file for program to write to the right half
  144.                      of the monochrome screen
  145.  
  146.  
  147.           Each of the executable files should run on your system.  It is
  148.        recommended that you run the MDSP bat file and the MDSPDEMO program
  149.        to verify compatabilibty with your system.
  150.  
  151.           Your cooperation in ensuring that everyone gets a complete copy of
  152.        of this software is appreciated.
  153.  
  154.  
  155.                              Purpose of this Software
  156.                              ------------------------
  157.  
  158.  
  159.           This software is intended to allow the user to access two monitors
  160.        from a user written program.  Currently, that program must be written
  161.        in Microsoft C or a compatable compiler and linked with Microsoft's
  162.        link editor.  Future versions may be available for other compilers.
  163.        The software will perform the following funtions:
  164.  
  165.             *  Check for availability of a monochome card and, if available
  166.                initialize it.
  167.  
  168.         *  Create a default (full screen) window and from 0 to 15 user
  169.                (partial screen) windows.  The routines will edit window
  170.                requests to insure that they do not overlap (except with
  171.                the default window).  User windows can also be destroyed,
  172.                allowing the screen space to be reused.
  173.  
  174.             *  Allow the user to enable or disable the monochrome screen.
  175.                This is a screen saving feature which is under the control of
  176.                of the programmer (it is not automatic).
  177.  
  178.             *  Routines are available to clear a window, scroll a window,
  179.                write a character to a window, write a string to a window,
  180.                set the cursor position in a window, and get the cursor
  181.                position (and window size) from a window.  All these routines
  182.                can be issued against either the default or a user window.
  183.  
  184.  
  185.  
  186.                                Future Enhancements
  187.                                -------------------
  188.  
  189.  
  190.           Future enhancements to this software will be made to correct errors
  191.        and add new features.  The current list of enhancements that are being
  192.        considered includes:
  193.  
  194.             *  Support for additional compilers.  Support for MSC V5.0 (no
  195.                changes likely) and Turbo Pascal V4.0 will be provide when
  196.                the compiler is received (real soon now).
  197.  
  198.             *  Performance improvements.  The screen write facility is much
  199.                slower than desired.  Significant pieces of these routines
  200.                will be rewritten, probably in assembler, to increase the
  201.                performance.
  202.  
  203.             *  Support for addition output options.  Currently, all windows
  204.                emulate TTY like output (with a cursor positioning function).
  205.                Additional options will be provided including; a no-scrolling
  206.                option, a no-line wrap option, overlapping windows, and ansi
  207.                or other terminal emulation routines.
  208.  
  209.             *  Support for Hercules compatable graphics.  Currently, these
  210.                routines support the output of text and character graphics.
  211.                Future versions may add support for monochrome graphics when
  212.                used with a Hercules or compatable monochrome graphics card.
  213.  
  214.             *  Implementation of these routines as a true DOS device driver.
  215.  
  216.             *  Other enhancements that may be suggested by users of the
  217.                software.
  218.  
  219.                               Your Rights as a User
  220.                               ---------------------
  221.  
  222.  
  223.           The author provides this software, as is, with no warranties
  224.        express or implied including the warranties of MERCHANTABILITY and
  225.        fitness for the specific purpose intended by the user.  It is expected
  226.        that most users will inspect and use the software prior to making any
  227.        payment to the author.
  228.  
  229.           The medium that the software is supplied on is not warranted by the
  230.        author.  If the medium was received directly from the author and is
  231.        not readable, please return it and a replacement will be supplied.
  232.        You may freely copy  and distribute this software, as well as make a
  233.        sufficient number of backups for yourself.  Please be sure that all
  234.        copies that you distribute are complete and unmodified.
  235.  
  236.           If you are having any difficulty with the software, please write to
  237.        the author, and I will make every attempt to clarify and correct the
  238.        problem.  Priority will be given to the correction of errors reported
  239.        by registered users.  No telephone support is available at this time.
  240.        I am normally available through EXEC-PC (414-963-2889).  I will
  241.        respond to questions addressed to me and will make sure that a current
  242.        version of this software is available there.  You will have to make
  243.        your own arrangements to access EXEC-PC since registration is
  244.        required.
  245.  
  246.                         Routine Specific Documentation
  247.                         ------------------------------
  248.  
  249.  
  250.      Routine Specific Variables:
  251.      ---------------------------
  252.  
  253.     The "MDISPLAY.H" file contains variable and function definitions that
  254.      are required to allow a  MS C program to call these functions.  The
  255.      variables and functions included in this file are specified in this
  256.      section.  The functions are described in detail in subsequent sections.
  257.  
  258.  
  259.         The following values are defined.  These values may be returned by
  260.      function calls to indicate call status information.  See the function
  261.      documentation for the values that will be returned.
  262.  
  263.              FALSE      0
  264.              TRUE       1
  265.              ERROR     -1
  266.  
  267.         The variable maxMwin is available to allow the a program to
  268.      determine the number of user windows available.  This version
  269.      defines the number of user windows as 15.  This cannot be changed
  270.      without recompiling the Mdisplay program itself.  If you, as the
  271.      user require more than 15 user windows, write me and I will
  272.      increase that number.  This value may be made user definable in
  273.      a future release if there appears to be a need for it.
  274.  
  275.         The following structure is used to return window information on
  276.      request.  A variable with this structure is returned as the second
  277.      parameter of the get window status (getMwinStatus) function call.
  278.  
  279.        struct   mwctl {
  280.           int   mwin;          /*  Window number            */
  281.           int   x1,y1,x2,y2;   /*  Window location / size   */
  282.           int   line;          /*  Current line number      */
  283.           int   column;        /*  Current column number    */
  284.           };
  285.  
  286.  
  287.         The following functions are available for calls by a user program.
  288.      These functions perform the functions described in this document.  Each
  289.      function is described, in turn, on the following pages.
  290.  
  291.              initMono();
  292.              initMwin();
  293.              createMwin(int, int, int, int);
  294.              destroyMwin(int);
  295.              clearMwin(int);
  296.              scrollMwin(int, int);
  297.              setMwin(int, int, int);
  298.              writeStringToMwin(int, void *, char);
  299.              writeCharToMwin(int, char, char);
  300.              getMwinStatus(int, mwctl *);
  301.              enableMwin();
  302.              disableMwin();
  303.  
  304.  
  305.              initMono()
  306.      ------------------
  307.  
  308.         The initMono function performs a complete initialization of the
  309.      monochrome system.  This process includes; initializing the MDISPLAY
  310.      internal variables, verifying the existance of a monochrome card,
  311.      verifying that the monochrome card is not the primary display,
  312.      initializing the monochrome card registers, and initializing the
  313.      monochrome video buffer.  This function will return either zero
  314.      (the default window number) or ERROR (-1).  When called, this function
  315.      should always be checked for a return of ERROR.  If ERROR is returned,
  316.      these routines should not be used.  This function can be called to
  317.      determine whether a usable secondary monitor is available.  It will
  318.      not, however, be able to detect whether the secondary monitor is in
  319.      use by another program as a secondary monitor.  In most cases, the
  320.      return from this function can be used to configure a program's output
  321.      (i.e., if the return is zero, use both the primary monitor and these
  322.      functions, otherwise use only the primary monitor).
  323.  
  324.      Warning:  This function uses the existance actual memory at segment
  325.            address B400 to determine whether a monochrome card is
  326.            present.  This technique is same as the one used by the
  327.            PC-DOS mode command.  This method can be fooled by memory
  328.            cards that are capable of using unused portions of the
  329.            video address space.  I am not personally aware of any
  330.            that use the monochrome video area, but I suspect that
  331.            there are some available.  If you have such a card, then
  332.            this function will not return an error and will initialize
  333.            the video area to blanks.  This may cause problems if other
  334.            programs are using the area to store data.
  335.  
  336.      Parameters:
  337.          None.
  338.  
  339.      Return values:  (int)
  340.          Zero (default window number)
  341.          ERROR (no monochrome card or it is primary)
  342.  
  343.      Example:
  344.          if (initMono() == ERROR)
  345.             {  printf("Error in initializing mono card.  ");
  346.                printf("Program being terminated.\n");
  347.                exit();   }
  348.  
  349.          This example will initialize the monochrome card and create the
  350.          default (full screen) window.  If an error is detected (no card
  351.          or primary) an error message will be displayed on the primary
  352.      display and the program terminated.
  353.  
  354.              initMwin()
  355.      ------------------
  356.  
  357.         The initMwin function is similar to the initMono function except that
  358.      only the MDISPLAY internal variables are initialized.  The monochrome
  359.      card verification and initialization logic is bypassed and no ERROR
  360.      processing occurs.  This function should only be used if the initMono
  361.      function cannot be, and only after appropriate error processing and
  362.      initialization has been performed.  This function will always return
  363.      a zero (the default window number).
  364.  
  365.         Since this function does not initialize the monochrome card or the
  366.      video buffer, it can be used when sharing of the secondary monitor is
  367.      required.  It is up to the programmer to insure that the programs
  368.      accessing the secondary monitor do not conflict.  An example of this
  369.      use is contained in the MDSP programs (MDSPI, MDSP1, and MDSP2).  The
  370.      first program (MDSPI) uses initMono to initialize the monochrome card
  371.      and quits.  The other two programs (MDSP1 and MDSP2) use this function
  372.      to initialize the internal variables and use the createMwin (see below)
  373.      to create a window that uses half the monochrome display (left and
  374.      right half respectively).  These programs allow the two halves of the
  375.      secondary monitor to be used independently.
  376.  
  377.         Although not recommended, this function also allows these routines
  378.      to be used to access a primary monochrome monitor.  This function will
  379.      initialize the internal variables and the default window even though
  380.      the monochrome monitor is currently primary.  A createMwin call can
  381.      be made to specify a portion of the display to write on.  The problem
  382.      with this approach is that output to the primary display that does not
  383.      use these routines (i.e., printf(...)) can write over this window or
  384.      cause it to be scrolled.  In some cases, this may still be a useful
  385.      tool.
  386.  
  387.      Parameters:
  388.          None.
  389.  
  390.      Return values:  (int)
  391.          Zero (default window number)
  392.  
  393.      Example:
  394.          initMwin();
  395.  
  396.          This example will initialize the MDISPLAY internal variables and
  397.          create the default (full screen) window.  No error checking is
  398.          performed.  When this function is used, it is assumed that you, the
  399.          programmer know the hardware configuration and how it is being used.
  400.  
  401.              createMwin(int, int, int, int)
  402.      --------------------------------------
  403.  
  404.         The createMwin function allocates a portion of the screen and
  405.      returns a number which allows the program to access that portion
  406.      or window.  This process includes; verifying that the parameters
  407.      are valid, verifying that the requested portion of the screen is
  408.      not already allocated, initialize the internal window variables,
  409.      and clear the window area.  This function will return either the
  410.      new window's number or ERROR (-1).  When called, this function
  411.      should always be checked for a return of ERROR.  If ERROR is returned,
  412.      the requested window is not available and should not be used in any
  413.      calls to Mwin functions.  This version of the Mwin routines does
  414.      not support overlapping windows, nor is it able to detect whether
  415.      the requested portion of the screen is being used by another program.
  416.         This function can only be called after a call to initMono or
  417.      initMwin.  If this function is called without the Mwin variables
  418.      being properly initialized, the function will return an ERROR
  419.      value.
  420.  
  421.      Parameters:
  422.          Upper left corner (int, int)
  423.          Lower right corner (int, int)
  424.  
  425.          Both the upper left corner and the lower right corner are
  426.          relative to (0,0) as the upper left corner of the screen.
  427.          On most monochrome monitors this results in a default window
  428.          of (0,0), (24,79).  The default window (window zero) does
  429.          not have to be created using this function, it is created
  430.          by the initMono or initMwin functions.
  431.  
  432.      Return values:  (int)
  433.          Window (the number associated with the new window)
  434.          ERROR (the requested window could not be allocated)
  435.  
  436.      Example:
  437.          wind1 = createMwin(1,1,12,12);
  438.          if (wind1 == ERROR)
  439.             {  printf("Error in creating window 1.  ");
  440.                printf("Program being terminated.\n");
  441.                exit();   }
  442.  
  443.          This example will create a window with an upper left corner of
  444.          (1,1) and a lower right corner of (12,12).  Both the starting
  445.          and ending points are relative to (0,0) in the upper left corner
  446.          of the screen.  If an error is detected (overlapping windows)
  447.          an error message will be displayed on the primary display and
  448.          the program terminated.
  449.  
  450.  
  451.              destroyMwin(int)
  452.      ------------------------
  453.  
  454.         The destroyMwin function frees the portion of the screen that
  455.      is allocated to the window that is being destroyed.  This allows
  456.      that portion of the screen to be allocated to a new window.  The
  457.      process of destroying a window includes verifying that the
  458.      requested window number is a valid window number, verifying that
  459.      it references an allocated window, and verifying that it is not
  460.      the default window.  This function will return either a value of
  461.      TRUE (1) or ERROR (-1).  It is only necessary to check for the
  462.      ERROR return if it is important that this routine succeeds.  In
  463.      other cases the return value from this function can be ignored.
  464.         This function can only be called after a call to initMono or
  465.      initMwin.  If this function is called without the Mwin variables
  466.      being properly initialized, the function will return an ERROR
  467.      value.
  468.  
  469.      Parameters:
  470.          Window (int)
  471.  
  472.          The Window parameter is normally a variable whose value was
  473.          returned from a call to the createMwin function. It is not
  474.          possible to destroy the default window (window zero).
  475.  
  476.      Return values:  (int)
  477.          TRUE (the window has been destroyed)
  478.          ERROR (the window could not be destroyed)
  479.  
  480.      Example:
  481.          if (destroyMwin(wind2) == ERROR)
  482.             {  printf("Error in destroying window 2.  ");
  483.                printf("Program being terminated.\n");
  484.                exit();   }
  485.  
  486.          This example will destroy (free) the window referenced by the
  487.          variable wind2.  If an error is detected (window not defined)
  488.          an error message will be displayed on the primary display and
  489.          the program terminated.
  490.  
  491.              clearMwin(int)
  492.      ----------------------
  493.  
  494.         The clearMwin function blanks the portion of the screen that
  495.      is allocated to the window that is being cleared.  The process of
  496.      clearing a window includes verifying that the requested window
  497.      number is a valid window number and verifying that it references
  498.      an allocated window or the default window.  This function will
  499.      return either a value of TRUE (1) or ERROR (-1).  The return value
  500.      from this routine should be checked to verify that the window is
  501.      now clear.
  502.         This function can only be called after a call to initMono or
  503.      initMwin.  If this function is called without the Mwin variables
  504.      being properly initialized, the function will return an ERROR
  505.      value.
  506.  
  507.      Parameters:
  508.          Window (int)
  509.  
  510.          The Window parameter is normally a variable whose value was
  511.          returned from a call to the createMwin function. If the parameter
  512.          is zero (or a variable with zero value) the whole screen will
  513.          be cleared.
  514.  
  515.      Return values:  (int)
  516.          TRUE (the window has been cleared)
  517.          ERROR (the window could not be cleared)
  518.  
  519.      Example:
  520.          if (clearMwin(wind2) == ERROR)
  521.             {  printf("Error in clearing window 2.  ");
  522.                printf("Program being terminated.\n");
  523.                exit();   }
  524.  
  525.          This example will clear (blank) the window referenced by the
  526.          variable wind2.  If an error is detected (window not defined)
  527.          an error message will be displayed on the primary display and
  528.          the program terminated.
  529.  
  530.          clearMwin(0);
  531.  
  532.          In the second example the entire screen will be cleared.  This
  533.      function call will always succeed unless the internal variables
  534.          have not been initialized.
  535.  
  536.              scrollMwin(int, int)
  537.      ----------------------------
  538.  
  539.         The scrollMwin function scrolls the portion of the screen that
  540.      is allocated to the window that is being scrolled.  The number of
  541.      lines that the window is scrolled is specified as the second
  542.      parameter.  The process of scrolling a window includes verifying
  543.      that the requested window number is a valid window number, verifying
  544.      that it references an allocated window or the default window, and
  545.      verifying that the scroll amount is greater than zero and not
  546.      greater than the window height.  If all edits succeed, each line
  547.      in the window will be moved up the scroll amount and the bottom
  548.      lines (the number will be equal to the scroll amount) will be
  549.      blanked and the cursor placed at the beginning of the first newly
  550.      blanked line.  This function will return either a value of TRUE (1)
  551.      or ERROR (-1).  The return value from this routine should be
  552.      checked to verify that the window has been scrolled.
  553.         This function can only be called after a call to initMono or
  554.      initMwin.  If this function is called without the Mwin variables
  555.      being properly initialized, the function will return an ERROR
  556.      value.
  557.  
  558.      Parameters:
  559.          Window (int)
  560.          Scroll amount (int)
  561.  
  562.          The Window parameter is normally a variable whose value was
  563.          returned from a call to the createMwin function. If the parameter
  564.          is zero (or a variable with zero value) the whole screen will
  565.          be scrolled.
  566.  
  567.          The scroll amount is the number of lines that the window will
  568.          be scrolled.  This number must be greater than zero and less
  569.          than the number of lines on the screen (actually, a value equal
  570.          to the number of lines is allowed but it becomes a very slow
  571.          clearMwin).
  572.  
  573.      Return values:  (int)
  574.          TRUE (the window has been scrolled)
  575.          ERROR (the window could not be scrolled)
  576.  
  577.      Example:
  578.          if (scrollMwin(wind2, 1) == ERROR)
  579.         {  printf("Error in scrolling window 2.  ");
  580.                printf("Program being terminated.\n");
  581.                exit();   }
  582.  
  583.          This example will scroll the window referenced by the variable
  584.          wind2 one line down.  If an error is detected, an error message
  585.          will be displayed on the primary display and the program
  586.          terminated.
  587.  
  588.      scrollMwin(0, 2);
  589.  
  590.          In the second example the entire screen will be scrolled two
  591.      lines.  This fuction call will always succeed unless the internal
  592.      variables have not been initialized.
  593.  
  594.  
  595.              writeCharToMwin(int, char, char)
  596.      ----------------------------------------
  597.  
  598.         The writeCharToMwin function writes one character to the portion
  599.      of the screen that is allocated to the window referenced in the
  600.      Window parameter.  The location that the character is written to
  601.      is dependent on previous commands to the window (the screen location
  602.      is saved across window calls).  The attribute that the character will
  603.      take is specified by the attribute parameter.  This value represents
  604.      the values allowed by the M6845 CRT controller (see table below).
  605.      This version supports all escape sequences defined by MSC version 4.0
  606.      and the special characters <bell>, <BS>, <LF>, <FF>, and <CR>.
  607.      In this implementation <BS> is limited to the current line, both
  608.      <CR> and <LF> are required for a new line, and <FF> is equivalent
  609.      to a clearMwin call.  All windows perform automatic line wrapping
  610.      and window scrolling if the end of a line or the end of the window
  611.      is reached.  The process of writing to a window includes verifying
  612.      that the requested window number is a valid window number, verifying
  613.      that it references an allocated window or the default window, and
  614.      actually writing the requested character to the window.  Neither
  615.      the character being displayed nor the attribute are verified to
  616.      insure that they will actually appear on the screen.  It is
  617.      possible to write non-displayable characters to the window or to
  618.      select a non-display attribute for the character being written.
  619.      This function will return either a value of TRUE (1) or ERROR (-1).
  620.      The return value from this function should be checked to verify that
  621.      the character was written to the window.
  622.         This function can only be called after a call to initMono or
  623.      initMwin.  If this function is called without the Mwin variables
  624.      being properly initialized, the function will return an ERROR
  625.      value.
  626.  
  627.      Parameters:
  628.          Window (int)
  629.          Character (char)
  630.          Attribute (char)
  631.  
  632.          The Window parameter is normally a variable whose value was
  633.          returned from a call to the createMwin function. If the parameter
  634.          is zero (or a variable with zero value) the default window will
  635.          be used (full screen).
  636.  
  637.          The character parameter specifies the character that will be
  638.          displayed on the window or the control information that will
  639.          be used to determine the next output position.
  640.  
  641.          The attribute parameter specifies the attribute that the
  642.          displayed character will have within the window.  The encoded
  643.          values for this character are:
  644.           0x80  -  character blink
  645.               0x70  -  reverse video
  646.               0x08  -  high intensity
  647.               0x07  -  normal intensity
  648.               0x01  -  underline
  649.          If no attributes other than blink and high intensity are specified
  650.          (0x00, 0x08, 0x80, or 0x88) then the character will not be
  651.          displayed.  The reverse video attribute is ignored if either the
  652.          normal intensity or the underline attribute is specified.  The
  653.          high intensity attribute is ignored if the reverse video attribute
  654.      is used (0x78 and 0xF8).
  655.  
  656.  
  657.      Return values:  (int)
  658.          TRUE (the character has been written)
  659.          ERROR (the character could not be written)
  660.  
  661.      Example:
  662.      if (writeCharToMwin(wind2,'A', 0x0F) == ERROR)
  663.         {  printf("Error in writing to window 2.  ");
  664.                printf("Program being terminated.\n");
  665.                exit();   }
  666.  
  667.      This example will write the character "A" on the secondary monitor
  668.      with a high intensity (displayed) attribute.  The character will
  669.      be displayed at the current window position.
  670.  
  671.              writeStringToMwin(int, void *, char)
  672.      --------------------------------------------
  673.  
  674.     The writeStringToMwin function writes a string to the portion of
  675.      the screen that is allocated to the window referenced in the Window
  676.      parameter.  The location that the string is written to is dependent
  677.      on previous commands to the window (the screen location is saved
  678.      across window calls).  The attribute that the string will take is
  679.      specified by the attribute parameter.  This value represents the
  680.      values allowed by the M6845 CRT controller (see table above).
  681.      This version supports all escape sequences defined by MSC V4.0
  682.      and the special characters <bell>, <BS>, <LF>, <FF>, and <CR>.
  683.      In this implementation <BS> is limited to the current line, both
  684.      <CR> and <LF> are required for a new line, and <FF> is equivalent
  685.      to a clearMwin call.  All windows perform automatic line wrapping
  686.      and window scrolling if the end of a line or the end of the window
  687.      is reached.  The process of writing to a window includes verifying
  688.      that the requested window number is a valid window number, verifying
  689.      that it references an allocated window or the default window, and
  690.      actually writing the requested string to the window.  Neither the
  691.      character being displayed nor the attribute are verified to insure
  692.      that they will actually appear on the screen.  It is possible to
  693.      write non-displayable characters to the window or to select a
  694.      non-display attribute for the character being written.  This function
  695.      will return either a value of TRUE (1) or ERROR (-1).  The return
  696.      value from this routine should be checked to verify that the
  697.      string was written to the window.
  698.     This function can only be called after a call to initMono or
  699.      initMwin.  If this function is called without the Mwin variables
  700.      being properly initialized, the function will return an ERROR
  701.      value.
  702.  
  703.      Parameters:
  704.      Window (int)
  705.      String (char[])
  706.      Attribute (char)
  707.  
  708.      The Window parameter is normally a variable whose value was
  709.      returned from a call to the createMwin function. If the parameter
  710.      is zero (or a variable with zero value) the default window will
  711.      be used (full screen).
  712.  
  713.      The string parameter specifies the string that will be displayed
  714.      on the window.  The string can include control information to
  715.      control the formatting of the string or to change the next output
  716.      position that will be used for the next window call.  The string
  717.      must be terminated with a hex zero character.
  718.  
  719.      The attribute parameter specifies the attribute that the
  720.      displayed character will have within the window.  See the
  721.      writeCharToMwin description for details on this parameter.
  722.  
  723.      Return values:  (int)
  724.      TRUE (the string has been written)
  725.      ERROR (the string could not be written)
  726.  
  727.      Example:
  728.      writeStringToMwin(wind2,"This is a test string.\n", 0x0F);
  729.  
  730.      This example will write a string on the secondary monitor and
  731.      position the output location at the start of the next line of
  732.      text for the window.  In this example, the return code is not
  733.      checked.
  734.  
  735.              setMwin(int, int, int)
  736.      ------------------------------
  737.  
  738.     The setMwin function changes the starting location for the next
  739.      screen write for a particular window.  This function allows these
  740.      routines to be used in programs that require non-TTY screen
  741.      formatting.  The process of changing the window location includes
  742.      verifying that the requested window number is a valid window number,
  743.      verifying that it references an allocated window or the default
  744.      window, verifying that the requested location is within the requested
  745.      window, and actually changing the control information that specifies
  746.      the output location.  This function will return either a value of
  747.      TRUE (1) or ERROR (-1).  The return value from this routine should
  748.      be checked to verify that the output location for the window was
  749.      changed.
  750.     This function can only be called after a call to initMono or
  751.      initMwin.  If this function is called without the Mwin variables
  752.      being properly initialized, the function will return an ERROR
  753.      value.
  754.  
  755.      Parameters:
  756.      Window (int)
  757.      X value (int)
  758.      Y value (int)
  759.  
  760.      The Window parameter is normally a variable whose value was
  761.      returned from a call to the createMwin function. If the parameter
  762.      is zero (or a variable with zero value) the default window will
  763.      be used (full screen).
  764.  
  765.      The X value is the output column where the next write will start.
  766.      This column number is relative to zero, with zero being the first
  767.      column, one being the second, etc.  If this value is negative or
  768.      greater than the number of columns in the window minus one, the
  769.      request will be rejected and the output position will not be
  770.      changed.
  771.  
  772.      The Y value is the output row where the next write will start.
  773.      This row number is relative to zero, with zero being the first
  774.      row, one being the second, etc.  If this value is negative or
  775.      greater than the number of rows in the window minus one, the
  776.      request will be rejected and the output position will not be
  777.      changed.
  778.  
  779.      Return values:  (int)
  780.      TRUE (the output position has been changed)
  781.      ERROR (the output position could not be changed)
  782.  
  783.      Example:
  784.      if (setMwin(wind2, 0, 4) == ERROR)
  785.         {  printf("Error in positioning on window 2.  ");
  786.            printf("Program being terminated.\n");
  787.            exit();   }
  788.  
  789.      This example will position the output at the start of the fifth
  790.      row on window "wind2".  If this requests fails, an error message
  791.      will be displayed on the primary screen and the program will be
  792.      terminated.
  793.  
  794.              getMwinStatus(int, mwctl *)
  795.      -----------------------------------
  796.  
  797.     The getMwinStatus function will return status information about
  798.      the requested window.  The information returned includes the window
  799.      number, the window location and size, and the output position within
  800.      the window.  The process of requesting the window status includes
  801.      verifying that the requested window number is a valid window number,
  802.      verifying that it references an allocated window or the default
  803.      window, and updating the window status structure provided by the
  804.      calling program (a pointer to this structure must be passed to this
  805.      function to allow it to be updated, see example below).  This
  806.      function will return either a value of TRUE (1) or ERROR (-1).  The
  807.      return value from this routine should be checked to verify that the
  808.      returned structure contains valid information about the window.
  809.     This function can only be called after a call to initMono or
  810.      initMwin.  If this function is called without the Mwin variables
  811.      being properly initialized, the function will return an ERROR
  812.      value.
  813.  
  814.      Parameters:
  815.      Window (int)
  816.      Status (mwctl)
  817.  
  818.      The Window parameter is normally a variable whose value was
  819.      returned from a call to the createMwin function. If the parameter
  820.      is zero (or a variable with zero value) the default window will
  821.      be used (full screen).
  822.  
  823.      The status parameter is a pointer to a structure of type "mwctl".
  824.      This structure is defined in the "MDISPLAY.H" include file (see
  825.      the variable definition section, above).  This parameter must be
  826.      passed via a pointer to it to allow the called function to update
  827.      the calling program's copy of the structure (see example, below).
  828.  
  829.      Return values:  (int)
  830.      TRUE (status for the requested window has been returned)
  831.      ERROR (status for the requested window could not be returned)
  832.  
  833.      Example:
  834.      #include <mdisplay.h>
  835.      struct  mwctl  mwin_status;
  836.      if (getMwinStatus(wind2, &mwin_status) == ERROR)
  837.         {  printf("Error in obtaining window status.  ");
  838.            printf("Program being terminated.\n");
  839.            exit();   }
  840.      printf("Status for window %i\n", mwin_status.mwin);
  841.      printf("  Current line:   %i\n", mwin_status.line);
  842.      printf("  Current column: %i\n", mwin_status.column);
  843.  
  844.      This example will retrieve status information about the window
  845.      "wind2".  It will display this information on the primary monitor.
  846.      If an error is encountered in retrieving the window status
  847.      information, an error message will be displayed on the primary
  848.      monitor and the program will be terminated.
  849.  
  850.              disableMwin()
  851.      ---------------------
  852.  
  853.     The disableMwin function will disable the monochrome card for
  854.      output.  When this is done, the screen information remains in the
  855.      video buffer but is not displayed on the monitor.  This function is
  856.      normally used as a screen saving function.  This function will have
  857.      no effect if there is not a monochrome card and monitor.
  858.     This function can be called at any time.  It does not require any
  859.      of the Mwin variables.  It can be used even if the monochrome monitor
  860.      is the primary monitor.  If this is done, the output to the monochrome
  861.      monitor will not be visible.
  862.  
  863.      Parameters:
  864.      None
  865.  
  866.      Return values:  (int)
  867.      FALSE (always)
  868.  
  869.      Example:
  870.      disableMwin();
  871.  
  872.      This example will disable the monochome monitor for output.  No
  873.      error checking is required for calls to this function.
  874.  
  875.  
  876.          enableMwin()
  877.      ---------------------
  878.  
  879.     The enableMwin function will enable the monochrome card for output.
  880.      When this is done, the screen information in the video buffer will be
  881.      displayed on the monitor.  This function is used to reverse the effect
  882.      of a call to the disableMwin function.  This function will have no
  883.      effect if there is not a monochrome card and monitor or if the output
  884.      has already been enabled.
  885.     This function can be called at any time.  It does not require any
  886.      of the Mwin variables.  It can be used even if the monochrome monitor
  887.      is the primary monitor.
  888.  
  889.      Parameters:
  890.      None
  891.  
  892.      Return values:  (int)
  893.      FALSE (always)
  894.  
  895.      Example:
  896.      enableMwin();
  897.  
  898.      This example will enable the monochome monitor for output.  No
  899.      error checking is required for calls to this function.
  900.  
  901.  
  902.  
  903.                             12: Comments and Feedback
  904.                             -------------------------
  905.  
  906.     Comments and feedback are always welcome.  You may send mail to:
  907.  
  908.  
  909.  
  910.                              William B. Bird
  911.                              9132 Surf Ct
  912.                              Brown Deer, WI, 53223
  913.  
  914.  
  915.  
  916.     Reports of significant errors or bugs will be accepted from anyone.
  917.      They will be corrected as soon as possible, whether or not the user
  918.      who reported the problem is registered.  A corrected version will be
  919.      uploaded to the EXEC-PC BBS as soon as the correction is made and
  920.      tested.  If other arrangements are required, please let me know and
  921.      I will try to accommodate them.
  922.  
  923.     Requests or suggestions for enhancements will also be accepted from
  924.      anyone.  In this case, however, priority will be given to the requests
  925.      of registered users.  The determining factor in classifying a request
  926.      as an enhancement or an error will be whether the actual operation of
  927.      the function corresponds to this document.  In most cases, if it does
  928.      not function as documented it will be considered to be an error, if it
  929.      does function as documented it will be considered to be an enhancement.
  930.  
  931.     All registered users will be notified of significant enhancements or
  932.      corrections to these routines.
  933.  
  934. -----------------------------------------------------------------------
  935.           R E G I S T R A T I O N    F O R M
  936. -----------------------------------------------------------------------
  937.  
  938.    Please register me as a user of the MDISPLAY routines.
  939.  
  940.  
  941.           _____________________________
  942.  
  943.           _____________________________
  944.  
  945.           _____________________________
  946.  
  947.  
  948.  
  949.    I have enclosed a _______ payment.  ($25.00 minimum for commercial use)
  950.  
  951.    The version of the routines that I am registering is ________ (see
  952. title page of this document).  All registered users who contribute $25.00
  953. or more (including commercial registration) will receive a copy of the most
  954. current (or next version if registering the most current) version of these
  955. routines by return mail.  Please make name and address legible to allow
  956. shipment.  The address must be capable of handling diskette sized mailers.
  957.  
  958.    I have read the following license agreement, and agree to abide by it:
  959.  
  960.  
  961.                           License Agreement:
  962.  
  963.  
  964.    The user receives a non-exclusive license to use the software refered
  965. to as the MDISPLAY utility routines on one computer (CPU).  This license
  966. in no way transfers the ownership of the actual software or the copyright
  967. thereon.  This license allows the licensee to make sufficient backup copies
  968. of the software as deemed necessary by the licensee.  The licensee may
  969. distribute copies of this software under the conditions described in the
  970. MDISPLAY document.  This license meets the registration requirements to
  971. allow the licensee to incorporate these routines into commercial products.
  972. The documentation provided with the MDISPLAY utility routines will be used
  973. in answering licensing questions not directly addressed by this license
  974. agreement.
  975.  
  976.  
  977.  
  978.  
  979.  
  980.               -------------          ---------------------------------
  981.                   Date                        Your signature
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990. ***************************************************************************
  991.  
  992.